Integration API
The Integration API is designed to facilitate data streaming, ensuring speed, efficiency, and compliance with established standards. It serves as a complementary alternative to OData extracts, particularly benefiting SSO users who previously could not utilize OData extracts. The Integration API enables these users to retrieve comparable data from ControliQ for use in custom reporting and spreadsheets. The Integration API also facilitates data-in as an alternative to manual data entry and connect.
Integration API endpoints available to customers (production) can be found on the following link: https://integration-api.workwareplus.com/index.html
Testing the Integration API
Try it out – Integration API Swagger page
The "try it out" feature lets users generate an Integration API request directly from the webpage. It's useful for creating requests, ensuring all necessary parameters are included, and checking parameter data types. Select an endpoint and click the down arrow to expand its options.
When using the try it out feature, ensure you are on the correct swagger page for the site & environment you are trying to get data from.
Once a request header is expanded, click Try it out and fill out your parameters.
|
Note: Not all parameters are always required. For example, if you choose a Rangetype which is ‘Last 30 days’, you may not need to apply a start or end date. You must consider the Data Type when entering these parameters. |
Once you have filled out the necessary parameters, select Execute
Selecting Execute will prompt a request URL to be generated, this can be used as the URL Request Header in your 3rd party software.
Integration API with excel (great for the endpoints with lots of data/complex data)
The Integration API can be used with many 3rd party software's. For this example, we are using Excel.
Open Excel, choose the Data tab and find and use the source ‘From Web’.
Paste the Request URL in the URL parts box. Under HTTP Request Headers, in the first dropdown, enter ‘Authorization’ and in the second text box enter ‘Bearer [Insert Access Token Here]‘ , ensure there is a space between Bearer and your Access Token, Click Ok.
Providing the request is valid an option to convert the Query to a table will appear, choose the option ‘To Table’ from the Transform tab:
Once ‘To Table’ is selected, click the Expand Icon to view the available columns:
Once expanded, choose the columns you wish to use in your Integration API request:
Select close and load after viewing the preview so that you can view and manipulate your Production data in the Workbook:
The data will then render in your Excel sheet:
Access Tokens & Permissions / Authorisation
Before the Integration API Endpoints can be utilised the user must have an Access Token. The access token is a bearer token which is administered within ControliQ > System Settings > Access Tokens. The Bearer token acts as your authorisation to make requests to Integration API endpoints.
Further information can be found in the System Settings section.
Access tokens admin
The access tokens administrator page is available through System Settings > Access Tokens. This is where Access Tokens are administered or revoked.
Issuing tokens & access tokens Setup
Prerequisites: To issue access tokens, a ControliQ user must have a role that includes the System Settings > Access Tokens permission.
To Issue a new token, Click the + arrow in the Access Tokens Admin page, next in the pop-up window, fill out the detail. More detail can be found within the System Settings section.
|
Expires on: This is the date the Token will expire; a token has a max life of 2 years from the date of issue.
Permission Areas: Tokens can give permissions to specific types of data access: Read, Create, or Update. These limit the API end points that the token allows access to use.
Workgroup: The Token Access Key can also be limited to accessing specific workgroups within the organization. This is based on the hierarchy of ControliQ, the token would allow data to be Read, Created, or Updated for all levels of the hierarchy at or below the chosen level.
Viewing and Storing the token
Once Access Token Setup is complete and save has been clicked. The token can be viewed once, the token should be stored securely and be kept private and only distributed to intended users / teams.
| Note: The token can only be viewed once. |
Integration API Endpoints
CaseData v1
GET – Endpoint for Streaming Case Data
-
Endpoint returns the top level Case data.
-
Useful for reporting on high level data points such as elapsed case time, total effort spent against a case, case closure date.
-
Pairs well with the data from the GET – Endpoint for Obtaining Case Worklog Data Endpoint.
Parameters
workgroupId: The workgroupId should represent the level in the hierarchy [department / team] that you want to run the extract for. You will only be able to retrieve data at or below the level that the Token was initially set to. If you enter 1 for workgroupId this will retrieve data for the Organization level and below.
Request Body
No Request Body required.
RangeType: This is the range in which you would like to query. Last30Days for example would show plans created in the Last 30 Days. Choosing custom allows you to set your own Start and End date for a given range.
StartDate and EndDate: Only applicable when RangeType of Custom is selected. Formats for StartDate and EndDate are yyyy-mm-dd and these represent the data ranges of the data you want to extract.
Response Body Fields
|
workgroupId |
Case Owner Workgroup ID. |
|
workgroup |
Case Owner Workgroup Name. |
|
category |
Case Category. |
|
type |
Case Type. |
|
elapsedTime |
Total elapsed time on the given Case. |
|
status |
Case Status. |
|
slaStartDate |
SLA Start date for the case. |
|
slaEndDate |
SLA End date for the case. |
|
closedDate |
Date a Case was closed. |
|
assignee |
Staffmember Assigned to the Case. |
|
totalEffortSpent |
total effort booked against the case to date. |
|
staffMemberId |
Unique Staffmember ID associated with the assignee. Use the GET - Endpoint for Staff Admin Data to obtain further staffmember details. |
|
refId |
Case Reference ID. |
|
caseCategoryId |
Unique identifier for Case Category. |
|
caseTypeId |
Unique identifier for the Case Type. |
Example Response Data
CaseWorklogData v1
GET – Endpoint for Obtaining Case Worklog Data
Parameters
workgroupId: The workgroupId should represent the level in the hierarchy [department / team] that you want to run the extract for. You will only be able to retrieve data at or below the level that the Token was initially set to. If you enter 1 for workgroupId this will retrieve data for the Organization level and below.
RangeType: This is the range in which you would like to query, Last30Days for example would show plans created in the Last 30 Days. Custom allows you to set your own Start and End date for a given range.
StartDate and EndDate: Only applicable when RangeType of Custom is selected. Formats for StartDate and EndDate are yyyy-mm-dd and these represent the data ranges of the data you want to extract.
Request Body
No Request Body required.
Response Body Fields
|
externalCaseId |
External Case Reference |
|
caseId |
CaseworkiQ Case Reference |
|
category |
Case Category |
|
type |
Case Type |
|
totalEffortSpentSeconds |
Total Effort Spent on a Task |
|
elapsedTimeDays |
Total time the case has been open |
|
status |
Case status |
|
creationDate |
Case creation date |
|
slaStartDate |
Service level agreement start date |
|
slaEndDate |
Service Level Agreement End Date |
|
closedDate |
Date the Case was closed. |
|
periodStartDate |
Period Start Date |
|
periodEndDate |
Period End Date |
|
team |
Team work was completed in |
|
staffMember |
Staffmember who completed the work |
|
date |
Date the effort was added to the worklog |
|
activity |
Type of Activity: Core, Downtime, Diverted or Break? |
|
task |
Name of the Activity Task |
|
startTimeUtc |
Start time of the given task |
|
endTimeUtc |
End time of the given task |
|
durationSeconds |
Duration spent on the task in seconds |
|
units |
Units of the task completed |
|
taskStage |
Task stage at date of record |
|
caseStage |
Case stage at date of record |
|
workgroupId |
Workgroup unique identifier for the team |
|
taskId |
Task unique identifier |
|
staffMemberId |
Staffmember unique identifier |
|
categoryId |
Category unique identifier |
|
typeId |
Type unique identifier |
|
referenceId |
Reference unique identifier |
|
caseStageId |
Case stage unique identifier |
Example Response Data
Diverted v1
GET – Get Diverted Activities (ID and Name only)
The endpoint enables API users to retrieve IDs and names of diverted tasks. This can be useful for:
-
Clients who need to maintain a lookup table at their end for ControliQ Diverted Task IDs and Names.
-
Clients who wish to use diverted task IDs in other API requests.
-
Use in external spreadsheets and reporting.
Parameters
No parameters necessary, returns all diverted tasks based on Token hierarchy level.
Request Body
None required.
Example Response data/Response Body Fields
Data is returned in JSON format.
|
Id |
The unique Identifier stored against the Diverted task in the Database |
|
Name |
The human readable name associated with a given id |
Response Codes
200 OK - Successful Response
400 Bad Request – Check parameters & request headers if applicable.
401 Unauthorized – Check Authorization Method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
POST – Create a Diverted task mapping.
Endpoint to be used when clients do not wish to maintain their own mappings and references. This endpoint allows API users to create source system mappings in a Diverted Task Reference table.
Parameters
No parameters necessary.
Request Body
| {
"mappingReferences": [ "string" ], "divertedTaskId": 0 } |
Mapping References: This refers to the specific string expected from the third party. It will be associated with the divertedTaskId that you provide in the same request body.
Diverted Task ID: This is the ControliQ diverted task identification number. When used in this endpoint, you are creating a reference string that links the divertedTaskId to the mappingReferences string. This can be obtained by the Get Diverted Activities endpoint.
Example Response body data / Response Body Fields
A successful response will return the Response Body in JSON format. The response consists of a JSON Object, which includes an Object Array named createdMappings.
This array contains keys for divertedMappingId, divertedTaskId, and mappingReference.
Example Request body
Example Response Body
The createdMappings array serves as the top-level element, indicating the mappings that have been generated from your request. Within this array:
• divertedMappingId: Represents the unique identifier of the mapping you have just created. This identifier may be required for deleting or updating a mapping.
• divertedTaskId: Denotes the divertedTaskId associated with the newly created mapping(s).
• mappingReference: Refers to the third-party reference linked to the divertedTaskId and the divertedMappingId that we have just created.
We can note from the Response that I have a divertedMappingId of 1, against the divertedTaskId 1 with mappingReference of ExternalDivertedTask. This means when we get sent ExternalDivertedTask via the Integration API, it can do a look up and resolve it as Diverted Task ID 1.
Response Codes
201 Created - Successful Response
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check Authorization Method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
GET – Get Diverted task mapping
Endpoint for retrieving Diverted task mappings
-
Useful for referencing IDs in other reports.
-
Allows an API user to view existing ControliQ cross references.
-
Helpful when creating, updating or deleting Diverted cross reference mappings.
-
Pulls back all Diverted Task Cross references.
-
Used to obtain Native ControliQ Diverted IDs stored against Source system references.
Parameters
No Parameters
Request Body
No Request Body required.
Example Response data / Response Body Fields
-
divertedMappingId: Represents the unique identifier of the mapping. This identifier may be required for deleting or updating a mapping.
-
divertedTaskId: Denotes the divertedTaskId associated with the mapping(s).
-
mappingReference: Refers to the third-party reference linked to the ControliQ divertedTaskId and the cross reference divertedMappingId.
-
divertedActivityName: The name of the diverted task, set in ControliQ Diverted Task Admin.
-
description: The description of the Diverted task, set in ControliQ Diverted Task Admin.
Response Codes
200 OK - Successful Response
400 Bad Request – Check parameters & request headers if applicable.
401 Unauthorized – Check authorization method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
PUT – Update a Diverted task mapping
Endpoint for updating existing Diverted task mapping string.
-
Useful when external system references change.
-
Useful for correcting mapping errors.
Parameters
No Parameters, data is handled in request body
Request Body
|
{
|
mappingId: The unique identifier of the mapping that you intend to modify.
mappingReference: The new string to replace the current mappingReference.
Example Response Data / Response Body Fields
In this example, we show the Diverted mapping references before and after this API has been executed. To obtain the before and after, use the GET – Get Diverted Task Mapping Endpoint.
Before:
We intend to update the Diverted task mapping with divertedMappingId: 1, we wish to change the mappingReference string “ExternalDivertedTasK” to “SourceSystemDivertedTask”. The request body should become:
| {
"mappingId": 1, "mappingReference": " SourceSystemDivertedTask" } |
The PUT request is made successfully, with response code of 200 OK.
After:
The Mapping now reflects the new mappingReference string:
Response Codes
200 OK - Successful request
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check authorization method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
DELETE – Delete a Diverted task mapping
Endpoint for deleting diverted task cross reference mappings.
-
Used when a mapping is no longer required.
-
Used to delete a mapping made by mistake.
Parameters
divertedMappingId: This is the divertedMappingId of the mapping you wish to delete. To obtain the divertedMappingId, follow the steps under the endpoint: GET – Get Diverted Task Mapping.
Request Body
No Request Body required.
Example Response Data / Response Body Fields
A successful deletion will not result in any response data. If an attempt to delete a mapping which doesn’t exist is made, then you will get a ‘Mapping Not Found’ response.
Response Codes
200 OK – Deletion Successful
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check authorization method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check the mapping ID, Check endpoint address, if correct, contact support.
Downtime v1
POST – Create a Downtime
Endpoint for creating downtime in ControliQ.
-
Used when adding downtime for the future, such as Annual Leave.
-
This can be useful when integrating with an HR system to maintain data consistency across various systems. It supports workforce management integration and provides a single source of truth.
-
This endpoint requires ControliQ native IDs for staffmembers and downtime tasks. We offer the customer an option to maintain their Downtime references within our lookup tables. See the following endpoints for more details on how to create and view: GET – Get Downtime task mapping,POST – Create a Downtime task mapping.
If the user is maintaining their own lookups, they can simply use the:
GET – Get Downtime activities (ID and Name only) Endpoint to pull our native IDs.
Parameters
No Parameters
Request Body
| {
"staffMemberId": 0, "downtimeTaskId": 0, "transactionUserName": "string", "startDateTime": "YYYY-MM-DDTHH:MM:SS", "endDateTime": " YYYY-MM-DDTHH:MM:SS", "timeUnit": "Seconds", "workingTimeType": "CustomTime", "duration": 999999999 } |
staffMemberId: StaffmemberId of the Staff Member you wish to add downtime for. This can be obtained from the GET - Endpoint for Staff Admin Data.
downtimeTaskId: downtimeTaskId of the Downtime Task you wish to add data for.
transactionUserName: Non-specific to controliq, this is something to tag your request with.
startDateTime: Start date of the downtime, supplied in YYYY-MM-DD format.
endDateTime: End date of the downtime, supplied in YYYY-MM-DD format.
timeUnit (can pass as string or id): This can be Seconds or 1, Minutes or 2, Hours or 3.
workingTimeType(Can pass as string or id): CustomTime or 1, HalfDay or 2, FullDay or 3.
duration: Duration of downtime to be posted, based on timeUnit metric.
Response Codes
200 OK - Successful Response
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check Authorization Method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
Example Scenarios
Scenario 1. Adding downtime for full days over a week period
e.g. Bob is on leave all week from 01/05/2024-07/05/2024
1. Staff member ID and Downtime ID are provided,
Customer can provide total staff complement as true to indicate the leave is for full days
2. From date and To date is provided
3. Duration is not populated
-
If any data already exists in the period provided, the data from the Integration API will overwrite existing data
-
This works the same for future absences and past absences
Exceptions
1. Staff member Id does not exist
2. Downtime task does not exist
3. To Date is before From Date
4. No period is selected
Scenario 2. Adding downtime for less than a full day over a week period.
e.g. Bob is off every morning from 01/05/2024-07/05/2024. If duration within the day is different for the selected period, each duration must be requested separately.
1. Staff member ID and Downtime activity ID are provided
2. Customer will provide total staff complement as false
3. From date and To date are provided
4. Duration is provided in minutes
5. If duration is provided over a range of dates - we assume same duration over multiple days
If duration is provided over multiple days, we are ignoring the time provided.
Exceptions
1. Staff member ID does not exist
2. Downtime task does not exist
3. To Date is before From Date
4. Duration provided is more than staff complement
GET – Get Downtime activities (ID and Name only)
The endpoint enables API users to retrieve IDs and names of diverted tasks. This can be useful for:
-
Clients who need to maintain a lookup table at their end for ControliQ Downtime Task IDs and Names.
-
Clients who wish to use Downtime task IDs in other API requests.
-
Use in external spreadsheets and reporting.
Parameters
No parameters necessary, returns all Downtime tasks based on Token hierarchy level.
Request Body
None required.
Example Response data / Response Body Fields
Data is returned in JSON format.
| Id | The unique Identifier stored against the Downtime task in the Database |
| Name | The human readable name associated with a given id |
Response Codes
200 OK - Successful Response
400 Bad Request – Check parameters & request headers if applicable.
401 Unauthorized – Check Authorization Method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
POST – Create a Downtime task mapping.
Endpoint to be used when clients do not wish to maintain their own mappings and references. This endpoint allows API users to create mapping references in a Downtime Task Reference table.
Parameters
No parameters necessary.
Request Body
| {
"mappingReferences": [ "string" ], "DowntimeTaskId": 0 } |
Mapping References: This refers to the specific string expected from the third party. It will be associated with the DowntimeTaskId that you provide.
Downtime Task ID: This is the ControliQ Downtime task identification number. When used in this endpoint, you are creating a reference string that links the downtimeTaskId to the mappingReferences string. This can be obtained by the Get Downtime Activities Endpoint.
Example Response body data / Response Body Fields
A successful response will return the Response Body in JSON format. The response consists of a JSON Object, which includes an Object Array named createdMappings. This array contains keys for downtimeMappingId, downtimeTaskId, and mappingReference.
Example Request body
Example Response Body
The createdMappings array serves as the top-level element, indicating the mappings that have been generated from your request. Within this array:
-
downtimeMappingId: Represents the unique identifier of the mapping you have just created. This identifier may be required for deleting or updating a mapping.
-
downtimeTaskId: Denotes the downtimeTaskId associated with the newly created mapping(s).
-
mappingReference: Refers to the third-party reference linked to the downtimeTaskId and the downtimeMappingId that we have just created.
We can note from the Response that I have a downtimeMappingId of 1, against the downtimeTaskId 1 with mappingReference of ExternalDowntimeTask. From this customers can pull our mappings, lookup their source system string and identify the downtimeTaskId which they need to use when creating a downtime.
Response Codes
201 Created - Successful Response
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check Authorization Method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
GET – Get Downtime task mapping
Endpoint for retrieving Downtime task mappings
-
Useful for referencing IDs in other reports.
-
Allows an API user to view existing ControliQ mapping references.
-
Helpful when creating, updating or deleting Downtime cross reference mappings.
-
Pulls back all Downtime Task Cross references.
Parameters
No Parameters
Request Body
No Request Body
Example Response data / Response Body Fields
-
downtimeMappingId: Represents the unique identifier of the mapping. This identifier may be required for deleting or updating a mapping.
-
downtimeTaskId: Denotes the downtimeTaskId associated with the mapping(s).
-
mappingReference: Refers to the third-party reference linked to the ControliQ downtimeTaskId and the cross reference downtimeMappingId.
-
downtimeActivityName: The name of the downtime task, set in ControliQ Downtime Task Admin.
-
description: The description of the Downtime task, set in ControliQ Downtime Task Admin.
Response Codes
200 OK - Successful Response
400 Bad Request – Check parameters & request headers if applicable.
401 Unauthorized – Check authorization method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
PUT – Update a Downtime task mapping
Endpoint for updating existing Downtime task mapping string.
-
Useful when external system references change.
-
Useful for correcting mapping errors.
Parameters
No Parameters, data is handled in request body
Request Body
| {
"mappingId": 0, "mappingReference": "string" } |
mappingId: The unique identifier of the mapping that you intend to modify.
mappingReference: The new string to replace the current mappingReference.
Example Response Data / Response Body Fields
In this example, we show the Downtime mapping references before and after this API has been executed. To obtain the before and after, use the GET – Get Downtime Task Mapping Endpoint.
Before:
We intend to update the Downtime task mapping with downtimeMappingId: 1, we wish to change the mappingReference string “ExternalDowntimeTasK” to “SourceSystemDowntimeTask”. The request body should become:
| {
"mappingId": 1, "mappingReference": " SourceSystemDowntimeTask" } |
If the PUT request is made successfully, a response code of 200 OK is returned.
After:
The Mapping now reflects the new mappingReference string:
Response Codes
200 OK - Successful request
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check authorization method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check endpoint address, if correct, contact support.
DELETE – Delete a Downtime task mapping
Endpoint for deleting downtime task cross reference mappings.
-
Used when a mapping is no longer required.
-
Used to delete a mapping made by mistake.
Parameters
downtimeMappingId: This is the downtimeMappingId of the mapping you wish to delete. To obtain the downtimeMappingId, follow the steps under the endpoint: GET – Get Downtime Task Mapping.
Request Body
No Request Body required.
Example Response Data / Response Body Fields
A successful deletion will not result in any response data. If an attempt to delete a mapping which doesn’t exist is made, then you will get a ‘Mapping Not Found’ response.
Response Codes
200 OK – Deletion Successful
400 Bad Request – Check parameters, request body & request headers if applicable.
401 Unauthorized – Check authorization method, Token (Incorrect, Permissions, Expired?) and Token permissions.
404 Not Found – Check the mapping ID, check endpoint address, if correct, contact support.
PlanData v1
GET - Endpoint for streaming PlanData
Parameters
workgroupId: The workgroupId should represent the level in the hierarchy [department / team] that you want to run the extract for. You will only be able to retrieve data at or below the level that the Token was initially set to. If you enter 1 for workgroupId this will retrieve data for the Organization level and below.
planUnit: Day, Week or Month. This reflects how plans are setup in ControliQ, you can have Daily, Weekly or Monthly plans, so choose the types of plans you are looking to find for the given range (RangeType).
RangeType: This is the range in which you would like to query, Last 30 Days for example would show plans created in the Last 30 Days. Custom allows you to set your own Start and End date for a given range.
StartDate and EndDate: Only applicable when RangeType of Custom is selected. Formats for StartDate and EndDate are yyyy-mm-dd and these represent the data ranges of the data you want to extract.
Request Body
No Request Body required.
Response Body Fields
|
startDate |
Start date of query range |
|
endDate |
End Date of query range |
|
workgroupId |
Workgroup associated with the plan owner’s workgroup. |
|
workgroupName |
Workgroup name of the plan owner. |
|
planRangeStartDate |
Start date of the plan range. |
|
planRangeEndDate |
End date of the plan range. |
|
planName |
Human readable plan name. |
|
category |
Category of data. for example: Work In, Work Out, Resource, etc. |
|
subCategory |
Sub category of the Category data, for example: Staff complement for Resource. |
|
item |
Item name of the category. |
|
itemType |
Item Type: Core, Diverted, downtime, etc. |
|
durationSeconds |
Expected duration of the item, in seconds. |
|
planUnitId |
Plan unit identifier. 1 – Day, 2 – Week, 3 – Month, 4 – Now Required. |
|
startDateId |
Start date of the query range in Integer form. |
|
endDateId |
End date of the query range in Integer form. |
|
taskId |
Task unique identifier. |
|
planId |
Plan unique identifier. |
|
units |
Units. |
Example Response Data
ProductionData v1
GET – Endpoint for Streaming Production Data
Parameters
workgroupId: The workgroupId should represent the level in the hierarchy [department / team] that you want to run the extract for. You will only be able to retrieve data at or below the level that the Token was initially set to. If you enter 1 for workgroupId this will retrieve data for the Organization level and below.
Category: The category specifies the data that is being extracted, as you have the option to only extract certain data if required. 0 = All, 1 = Work In, 2 = Work In Progress, 3 = Work Out, 4 = Diverted, 5 = Downtime, 6 = Resource
IncludeUnverifiedData: By default, this will be set as False meaning only data that has been verified in the Manage Data function will be extracted. To extract all captured data, select the true option from the drop-down menu.
RangeType: The range type determines the period of report Last 30 days, Last 60 days, Last 90 days, Custom [requires startDate and endDate], Last 7 days
StartDate and EndDates: Formats for StartDate and EndDate are yyyy-mm-dd and these represent the data ranges of the data you want to extract. If you use both a startDate and an endDate, you will need to select RangeType 4. If you use any other range type you only need to enter and endDate.
Request Body
No Request Body required.
Response Body Fields
|
workLocation |
Work location of the staffmember. |
|
workgroupId |
Unique identifier of the Workgroup. |
|
workgroupName |
Workgroup name. |
|
units |
Units completed. |
|
durationSeconds |
Duration in seconds completed. |
|
dateId |
Date identifier. |
|
category |
Activity type. |
|
startDate |
Start date of query range. |
|
endDate |
End date of query range. |
|
staffMemberId |
Unique identifier of the staff member. |
|
staffFirstName |
Staff member first name. |
|
staffLastName |
Staff member last name. |
|
staffReferenceId |
Staffmember reference. |
|
taskId |
Unique Identifier of the task. |
|
activity |
Activity name. |
|
employmentType |
Employment type of the staff member. |
Example Response Data
RtmStaffMemberActivityData v1
GET - Endpoint for streaming RTM StaffMember activity.
Parameters
WorkgroupId: Determines the level of the hierarchy you wish to return data for.
RangeType: Specifies the date range for which you want data to be returned.
StartDate and EndDate: Only applicable when RangeType of Custom is selected. Formats for StartDate and EndDate are yyyy-mm-dd and these represent the data ranges of the data you want to extract.
Request Body
No Request Body required.
Response Body Fields
|
groupId |
Group Identifier. |
|
date |
Date of activity in DD/MM/YYYY HH:MM format. |
|
workgroupId |
Workgroup identifier. |
|
workgroup |
Workgroup name. |
|
staffMemberName |
Staff member name. |
|
refId |
Reference Identifier. |
|
activity |
Activity name. |
|
startDate |
Start date of the activity in DD/MM/YYYY HH:MM format. |
|
endDate |
End date of the activity in DD/MM/YYYY HH:MM format. |
|
taskName |
Task name |
|
itemsCompleted |
Items completed (units) |
|
itemsCompletedSeconds |
Items completed in seconds. |
|
workoutTime |
Workout completed time in DD/MM/YYYY HH:MM format. |
|
taskId |
Task identifier. |
|
staffMemberId |
Staffmember identifier. |
|
activityTypeId |
Activity Type identifier. |
Example Response Data
SmartSkillsData v1
GET – Endpoint for Streaming Smart Skills Data
Parameters
WorkgroupId: Determines the level of the hierarchy you wish to return data for.
StartDate and EndDate: Formats for StartDate and EndDate are yyyy-mm-dd, this range represents the date scope of data you wish to return.
Request Body
No Request Body required.
Response Body Fields
|
dateId |
Date Identifier/Date as an integer, YYYYMMDD format. |
|
date |
Date in YYYY-MM-DDTHH:MM:SS format. |
|
staffMemberId |
Staff member identifier. |
|
staffReferenceId |
Staff member Reference identifier. |
|
staffMember |
Staff member name. |
|
coreTaskId |
Core Task identifier. |
|
coreTask |
Core Task name. |
|
workgroupId |
Workgroup identifier. |
|
workgroup |
Workgroup Name. |
|
skillLevel |
Skill level score. |
|
smartSkill |
Smart Skill Score. |
|
confidenceLevel |
Smart Skill Score Confidence Level. |
Example Response Data
StaffAdminData v1
GET - Endpoint for Staff Admin Data
Allows API users to get Staffmembers, IDs and other Staffmember Admin data.
Production Endpoint: https://integration-api.workwareplus.com/api/StaffAdminData/workgroups/{workgroupId}?includeUnassignedUsers=true
Parameters
WorkgroupId: Determines the level of the hierarchy you wish to return data for.
includeUnassignedUsers: Choose true to include all unassigned users, choose False to show only users who are assigned to the WorkgroupId that is passed in the parameters.
Request Body
No Request Body required.
Response Body Fields
|
staffMemberId |
Staff member unique identifier. |
|
staffMemberLastName |
Staff member last name. |
|
staffMemberFirstName |
Staff member first name. |
|
staffMemberMiddleName |
Staff member middle name. |
|
staffMemberFullName |
Staff member full name. |
|
area |
Area assigned to the staff member. |
|
location |
Location assigned to the staff member.q |
|
userTypeId |
User type 1 - Team Member, 2 - Team Leader, 3 - Senior Leader, 4 - Champion/Coach, 5 - Administrator, 6 – Robot. |
|
userType |
User type name. |
|
canLogIn |
Flag to show whether user can log in or not. |
|
activationStatusId |
Activation Status identifier. |
|
activationStatus |
Activation Status. |
|
lastActive |
date the account was last used to access ControliQ. |
|
authenticationTypeId |
Authentication Type identifier |
|
authenticationType |
Authentication Type |
|
|
Email address of the staff member. |
|
username |
Username of the User. |
|
capturesData |
Flag for data capture. |
|
jobTitle |
Job title of the staff member. |
|
refID |
Reference Id of the staff member. |
|
employeePositionId |
Employee position identifier. |
|
employeePosition |
The staff members position from the drop-down menu. The Employee Positions are defined by your organisation but typically represent different grades or bands for production staff. |
|
employmentTypeId |
Employment type identifier. |
|
employmentType |
Employment type name. |
|
workgroupId |
Owner workgroup identifier. |
|
team |
The team name the user is linked to. |
|
teamId |
Team identifier of the team that the user is linked to. |
|
firstDayOfWeek |
First working day of the week for the staffmember. |
|
defaultWorkingTimeDay1Seconds |
Default working time in seconds for each day of the week.
|
|
defaultWorkingTimeDay2Seconds |
|
|
defaultWorkingTimeDay3Seconds |
|
|
defaultWorkingTimeDay4Seconds |
|
|
defaultWorkingTimeDay5Seconds |
|
|
defaultWorkingTimeDay6Seconds |
|
|
defaultWorkingTimeDay7Seconds |
|
|
worksFrom |
Defines the date which the staffmember is active from. |
|
worksTo |
Defines the date which the staffmember is active to. |
|
holidays |
Displays the staff members yearly annual leave allowance if this field was populated during staff member setup. |
|
adjustmentTolerance |
This specifies at what point an individual's Time Worked flags amber in the Manage Data screen. |
|
positiveStaffAdjustmentTypeId |
positiveStaffAdjustment unique identifier. |
|
positiveStaffAdjustment |
Specifies how differences between a staff members Time Worked and Staff Complement should be treated. |
|
negativeStaffAdjustmentTypeId |
negativeStaffAdjustmentTypeId unique identifier. |
|
negativeStaffAdjustment |
Specifies how differences between a staff members Time Worked and Staff Complement should be treated. |
|
active |
Active flag for the user. |
|
startDate |
Start date. |
|
endDate |
End date. |
Example Response Data
WorkgroupPerformanceIndicators v1
GET - Endpoint for Workgroup Performance Indicators
Parameters
workgroupId: The workgroupId should represent the level in the hierarchy [department / team] that you want to run the extract for. You will only be able to retrieve data at or below the level that the Token was initially set to. If you enter 1 for workgroupId this will retrieve data for the Organization level and below.
PeriodType: Period type of data returned by the endpoint.
RangeType: This is the range in which you would like to query, Last 30 Days for example would show plans created in the Last 30 Days. Custom allows you to set your own Start and End date for a given range.
StartDate and EndDate: Only applicable when RangeType of Custom is selected. Formats for StartDate and EndDate are yyyy-mm-dd and these represent the data ranges of the data you want to extract.
Request Body
No Request Body required.
Response Body Fields
| date | Date in YYYY-MM-DDTHH:MM:SS format. |
| workgroupId | Workgroup Identifier. |
| workgroupName | Workgroup Name. |
| workInHours | Work In in hours. |
| workOutHours | Work Out in hours. |
| wipHours | Work In Progress in hours. |
| divertedHours | Diverted Time in hours. |
| downtimeHours | Downtime in hours. |
|
timeWorkedHours |
Time Worked in hours. |
|
coreTimeHours |
Core Time in hours. |
|
productivity |
Productivity score. |
|
utilisation |
Utilisation score. |
|
complexProductivity |
Complex Productivity score. |
|
totalProductivity |
Total Productivity. |
|
costPerStandardHourCur |
Cost per standard hour. |
|
errorRate |
Error rate. |
|
breachRate |
Breach Rate. |
Example Response Data
